A network protocol defines a set of rules for communication that must be followed by any application wishing to utilise the protocol. This appendix shall state and explain the specific messages that should be understood by applications using this protocol, along with examples of their usage.

As defined in the Protocol Design section, messages are split up into two distinct types: \textbf{action messages}, which consists of actions that a sender can perform on the receiver and expect a response stating the success of the action, and \textbf{request messages}, which expect some sort of data response from the receiver. All messages must be met with a response – there are no exceptions to this rule.

\section{Client Actions (pre-login)}

Prior to logging in, clients can only send a particular subset of action messages and no request messages. This includes the actions required to login and register an account. Once logged in, the user cannot send these messages again.

\begin{alltt}
\textbf{CA_LOGIN:<TRANSACTION ID>:<USERNAME>:<PASSWORD>}
\end{alltt}This command attempts to log the client in with the supplied details. A successful response denotes that the user has now logged in and can execute post-login commands. A failure response denotes that the user account does not exist, the supplied details are invalid, or the user is already logged in.
\begin{quote}
	\textit{Client:} \verb+CA_LOGIN:0:test@test.com:MyPassword+\newline
	\textit{Server:} \verb+CA_LOGIN:0:TRUE+\newline
	The user is now logged in and can execute post-login commands.
\end{quote}
\begin{quote}
	\textit{Client:} \verb+CA_LOGIN:1:test@test.com:WrongPassword+\newline
	\textit{Server:} \verb+CA_LOGIN:1:FALSE+\newline
	The supplied details are invalid, user must try to login again or register a new account.
\end{quote}

\begin{alltt}
\textbf{CA_REGISTER:<TRANSACTION ID>:<USERNAME>:<PASSWORD>}
	\end{alltt}
This command attempts to register a new account with the supplied details. A successful response denotes that the user account has been created, and can now login using those details. A failure response denotes that the account already exists.

\begin{quote}
\textit{Client:} \verb+CA_REGISTER:0:test@test.com:MyPassword+\newline
\textit{Server:} \verb+CA_REGISTER:0:TRUE+\newline
The account has been created and the user can now login.
\end{quote}

\section{Client Actions (post-login)}
After logging in he client can begin utilising the rest of the defined action and request messages. It must also be prepared to receive any actions or requests from the server.

\begin{alltt}
\textbf{CA_JOIN:<TRANSACTION ID>:<CHANNEL NAME>	}
		\end{alltt}
This command attempts to join the currently logged in user to the specified channel. The channel must be valid and unlocked, otherwise a failure response will be sent. A successful response means that the client can now send and receive messages from that channel, as well as performing requests on it to get the users currently in that channel.

\begin{quote}
\textit{Client:} \verb+CA_JOIN:0:chat123+\newline
\textit{Server:} \verb+CA_JOIN:0:TRUE+\newline
The user is now in the specified channel and can begin sending and receiving messages.
\end{quote}
\begin{alltt}
\textbf{CA_LEAVE:<TRANSACTION ID>:<CHANNEL NAME>	}
		\end{alltt}
This command causes the currently logged in user to leave the specified channel, providing they are already in that channel. A successful response denotes that the user has left the channel. A failure response is sent if the user was not already in that channel.

\begin{quote}
\textit{Client:} \verb+CA_LEAVE:0:chat123+\newline
\textit{Server:} \verb+CA_LEAVE:0:TRUE+\newline
The user has now left the specified channel and can no longer send or receive message.
\end{quote}
\begin{alltt}
\textbf{CA_LOCK:<TRANSACTION ID>:<CHANNEL NAME>:<TRUE | FALSE>	}
		\end{alltt}
This command sets the lock status for the specified channel to the specified channel. When a channel is locked, users may only join that channel if they have been invited. Any user in a channel may set the lock status. A successful response denotes that the lock status has been set. A failure response will be sent if the user is not in that channel.

\begin{quote}
\textit{Client:} \verb+CA_LOCK:0:chat123:TRUE+\newline
\textit{Server:} \verb+CA_LOCK:0:TRUE+\newline
The specified channel is now locked. Only users that have been invited to that channel may join it.
\end{quote}

\begin{quote}
\textit{Client:} \verb+CA_LOCK:1:chat123:FALSE+\newline
\textit{Server:} \verb+CA_LOCK:1:TRUE+\newline
The specified channel is unlocked. Any user may join the channel if they know it’s name.
\end{quote}
\begin{alltt}
\textbf{CA_INVITE:<TRANSACTION ID>:<USERNAME>:<CHANNEL NAME>	}
		\end{alltt}
This command causes a message to be sent to the specified user, inviting them to the specified channel. The user sending the invite must be in the specified channel, and the specified user must be logged in. This is mainly intended to allow users to join locked channels (e.g: for private chats). A successful response is sent if the invite has been sent. A failure response is sent if the user is not in the channel, or the specified user is not online.

\begin{quote}
\textit{Client:} \verb+CA_INVITE:0:otherUser@mail.com:chat123+\newline
\textit{Server:} \verb+CA_INVITE:0:TRUE+\newline
The specified user has been sent the invite, and can now join that channel if it was locked.
\end{quote}
\begin{alltt}
\textbf{CA_MSG:<TRANSACTION ID>:<CHANNEL NAME>:<MESSAGE>	}
		\end{alltt}
This command causes the specified message to be sent to the specified channel, relaying it to all other users in that channel. A successful response is sent if the message has been relayed. A failure response is sent if the currently logged in user is not in that channel.

\begin{quote}
\textit{Client:} \verb+CA_MSG:0:chat123:Hello, world!+\newline
\textit{Server:} \verb+CA_MSG:0:TRUE+\newline
The message has been relayed to all users in the channel.
\end{quote}

\begin{alltt}
\textbf{CA_PASSWORD:<TRANSACTION ID>:<CURRENT PASSWORD>:<NEW PASSWORD>	}
		\end{alltt}
This command causes the currently logged in user’s password to be changed to the specified new one, assuming that the supplied current password is correct. A successful response is sent if the password has been changed. A failure response is sent if the supplied current password was incorrect.

\begin{quote}
\textit{Client:} \verb+CA_PASSWORD:0:MyPassword:NewPassword+\newline
\textit{Server:} \verb+CA_PASSWORD:0:TRUE+\newline
The supplied current password is correct and the user’s password has been updated to the new supplied one.
\end{quote}
\begin{quote}
\textit{Client:} \verb+CA_PASSWORD:0:WrongPassword:NewPassword+\newline
\textit{Server:} \verb+CA_PASSWORD:0:FALSE+\newline
The current password supplied is incorrect and the user’s password has not been updated.
\end{quote}
\begin{alltt}
\textbf{CA_LOGOUT:<TRANSACTION ID>	}
		\end{alltt}
This command causes the currently logged in user to be logged out, allowing them to login again using their details if they wish. This command can only return a successful response as the user must already be logged in to execute it.

\begin{quote}
\textit{Client:} \verb+CA_LOGOUT:0+\newline
\textit{Server:} \verb+CA_LOGOUT:0:TRUE+\newline
The user is now logged out.
\end{quote}
\begin{alltt}
\textbf{CA_AVATAR:<TRANSACTION ID>:<BASE64-ENCODED JPEG IMAGE>	}
		\end{alltt}
This command uploads a new avatar image to the server for the currently logged in user, replacing the old one. The only argument sent must be a BASE64 encoded JPEG image as defined by the encoding section of the protocol design. A successful response is returned if the avatar has been updated successfully. A failure response is returned if the data was mangled in any way, or if the supplied file exceeded the avatar file size limit set by the server.

\begin{alltt}
\textbf{CA_ADDCC:<TRANSACTION ID>:<CHANNEL NAME>	}
		\end{alltt}
This command adds the specified channel to the currently logged in user’s contact list. A successful response is sent if the channel has been added to the contact list. A failure response is sent if the channel is already on the contact list.

\begin{quote}
\textit{Client:} \verb+CA_ADDCC:0:chat123+\newline
\textit{Server:} \verb+CA_ADDCC:0:TRUE+\newline
The specified channel will now appear on the user’s contact list upon requesting their contact list.
\end{quote}
\begin{alltt}
\textbf{CA_ADDUC:<TRANSACTION ID>:<USERNAME>	}
		\end{alltt}
This command adds the specified user to the currently logged in user’s contact list. A successful response is sent if the user has been added to the contact list. A failure response is sent if the user is already on the contact list, or if the user does not exist.

\begin{quote}
\textit{Client:} \verb+CA_ADDUC:0:otherUser@mail.com+\newline
\textit{Server:} \verb+CA_ADDUC:0:TRUE+\newline
The specified user will now appear on the currently logged in user’s contact list upon requesting their contact list.
\end{quote}
\begin{alltt}
\textbf{CA_REMCC:<TRANSACTION ID>:<CHANNEL NAME>}
		\end{alltt}
This command removes the specified channel to the currently logged in user’s contact list. A successful response is sent if the channel has been removed from the contact list. A failure response is sent if the channel is not already on the contact list.

\begin{quote}
\textit{Client:} \verb+CA_REMCC:0:chat123+\newline
\textit{Server:} \verb+CA_REMCC:0:TRUE+\newline
The specified channel will no longer appear on the user’s contact list upon requesting their contact list.
\end{quote}
\begin{alltt}
\textbf{CA_REMUC:<TRANSACTION ID>:<CHANNEL NAME>}
		\end{alltt}
This command removes the specified user to the currently logged in user’s contact list. A successful response is sent if the user has been removed from the contact list. A failure response is sent if the user is not already on the contact list, or the user does not exist.

\begin{quote}
\textit{Client:} \verb+CA_REMUC:0:otherUser@mail.com+\newline
\textit{Server:} \verb+CA_REMUC:0:TRUE+\newline
The specified user will no longer appear on the currently logged in user’s contact list upon requesting their contact list.
\end{quote}

%%%%%%%%%%%%%%%%%%%%%%%

\section{Client Requests}

A logged in client can make the following requests to the server at any point throughout the connection, expecting some data response for each message.

\begin{alltt}
\textbf{CR_GETUCONTACTS:<TRANSACTION ID>	}
			\end{alltt}
This command returns a listing of all users in the currently logged in user’s contact list. Each argument following the success argument is a single username from the contact list. The success argument for this message is always successful as every user has a contact list.

\begin{quote}
\textit{Client:} \verb+CR_GETUCONTACTS:0+\newline
\textit{Server:} \verb+CR_GETUCONTACTS:TRUE:otherUser@mail.com:another@gmail.com+
\end{quote}
\begin{alltt}
\textbf{CR_GETCCONTACTS:<TRANSACTION ID>	}
			\end{alltt}
This command returns a listing of all channels in the currently logged in user’s contact list. Each argument following the success argument is a single channel from the contact list. The success argument for this message is always successful as every user has a contact list.

\begin{quote}
\textit{Client:} \verb+CR_GETCCONTACTS:0+\newline
\textit{Server:} \verb+CR_GETCCONTACTS:TRUE:chat123:video_games:glasgow:teamK+
\end{quote}
\begin{alltt}
\textbf{CR_AVATAR:<TRANSACTION ID>:<USERNAME>	}
			\end{alltt}
This command returns the BASE64-encoded JPEG avatar image for the specified user. The command will be successful if the specified user exists. A failure response is returned if the specified user does not exist.

\begin{alltt}
\textbf{CR_USERLIST:<TRANSACTION ID>:<CHANNEL NAME>	}
			\end{alltt}
This command returns a listing of all users currently in the specified channel. Each argument following the success argument is a single user who is currently in the channel. The command will fail if the currently logged in user is not in the specified channel.

\begin{quote}
\textit{Client:} \verb+CR_USERLIST:0:chat123+\newline
\textit{Server:} \verb+CR_USERLIST:0:TRUE:otherUser@mail.com:another@gmail.com+
\end{quote}
\begin{alltt}
\textbf{CR_USERLIST:<TRANSACTION ID>:<CHANNEL NAME>	}
			\end{alltt}
This command returns a listing of all users currently in the specified channel. Each argument following the success argument is a single user who is currently in the channel. The command will fail if the currently logged in user is not in the specified channel.

\begin{quote}
\textit{Client:} \verb+CR_USERLIST:0:chat123+\newline
\textit{Server:} \verb+CR_USERLIST:0:TRUE:otherUser@mail.com:another@gmail.com+
\end{quote}
\begin{alltt}
\textbf{CR_USERINFO:<TRANSACTION ID>:<USERNAME>	}
			\end{alltt}
This command returns some information about the specified user, providing that user exists. The command will fail if the specified user does not exist. The format of the response is as follows, if successful:

\begin{alltt}CR_USERLIST:0:TRUE:<FIRST NAME>:<LAST NAME>:<EMAIL>:<DISPLAY NAME>:<STATUS>
			\end{alltt}
			
\begin{quote}
\textit{Client:} \verb+CR_USERLIST:0:otherUser@gmail.com+\newline
\textit{Server:} \verb+CR_USERLIST:0:TRUE:John:Smith:otherUser@mail.com:Johnny:ONLINE+
\end{quote}

\section{Server Actions}

Just as the client can perform actions on the server, the server can perform actions on the client. These are intended to notify the client of particular events and their details, such as when a user joins a channel or when a message is sent to a channel the client is in.

\begin{alltt}
\textbf{SA_JOIN:<TRANSACTION ID>:<USERNAME>:<CHANNEL NAME>	}
			\end{alltt}
This command is sent to users who are in the specified channel name when a new user joins that channel. The client should respond with a successful response, denoting that they have received the message.

\begin{quote}
\textit{Server:} \verb+SA_JOIN:0:otherUser@mail.com:chat123+\newline
\textit{Client:} \verb+SA_JOIN:0:TRUE+\newline
The specified user is now in the specified channel, and can send and receive messages to that channel.
\end{quote}
\begin{alltt}
\textbf{SA_LEAVE:<TRANSACTION ID>:<USERNAME>:<CHANNEL NAME>	}
			\end{alltt}
This command is sent to users who are in the specified channel name when a user leaves that channel. The client should respond with a successful response, denoting that they have received the message.

\begin{quote}
	\textit{Server:} \verb+SA_LEAVE:0:otherUser@mail.com:chat123+\newline
\textit{Client:} \verb+SA_LEAVE:0:TRUE+\newline
The specified user has now left the specified channel and can no longer receive or send messages to that channel.
\end{quote}
\begin{alltt}
\textbf{SA_INVITE:<TRANSACTION ID>:<USERNAME>:<CHANNEL NAME>	}
			\end{alltt}
This command is sent to a user when the specified user invites them to the specified channel. Following this invite, the receiving user may join that channel even if it is locked. The client should respond with a successful response, denoting that they have received the message; the successful response does not mean that the user has accepted the invite.

\begin{quote}
\textit{Server:} \verb+SA_INVITE:0:otherUser@mail.com:chat123+\newline
\textit{Client:} \verb+SA_INVITE:0:TRUE+\newline
The specified user has invited the receiving user to the specified channel. The receiving user can now join that channel even if it was locked.
\end{quote}
\begin{alltt}
\textbf{SA_MSG:<TRANSACTION ID>:<USERNAME>:<CHANNEL NAME>:<MESSAGE>	}
			\end{alltt}
This command is sent to a user when the specified user sends a message to the specified channel (that the receiving user is in). A successful response should be returned, denoting that the client has received the message.

\begin{quote}
\textit{Server:} \verb+SA_MSG:0:otherUser@mail.com:chat123:Hello, world!+\newline
\textit{Client:} \verb+SA_MSG:0:TRUE+
\end{quote}
\section{Heartbeat}

Periodically throughout a connection, the server will send a heartbeat action message to the client in order to determine if they are still connected and activate. The client must respond to this message with a successful response by the next heartbeat or they will be automatically disconnected.

\begin{quote}
\textit{Server:} \verb+SA_PING:0+\newline
\textit{Client:} \verb+SA_PING:0:TRUE+
\end{quote}
